home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / catD / pciio_intr.z / pciio_intr
Encoding:
Text File  |  2002-10-03  |  12.4 KB  |  265 lines
  1.  
  2.  
  3.  
  4. ppppcccciiiiiiiioooo____iiiinnnnttttrrrr((((DDDD3333))))                                                  ppppcccciiiiiiiioooo____iiiinnnnttttrrrr((((DDDD3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      pciio_intr: pciio_intr_alloc, pciio_intr_connect, pciio_intr_disconnect,
  10.      pciio_intr_free - manage PCI Interrupts
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////PPPPCCCCIIII////ppppcccciiiiiiiioooo....hhhh>>>>
  14.  
  15.      ppppcccciiiiiiiioooo____iiiinnnnttttrrrr____tttt
  16.      ppppcccciiiiiiiioooo____iiiinnnnttttrrrr____aaaalllllllloooocccc((((
  17.           vvvveeeerrrrtttteeeexxxx____hhhhddddllll____tttt _v_h_d_l,,,,
  18.           ddddeeeevvvviiiicccceeee____ddddeeeesssscccc____tttt _d_e_s_c,,,,
  19.           ppppcccciiiiiiiioooo____iiiinnnnttttrrrr____lllliiiinnnneeee____tttt _l_i_n_e_s,,,,
  20.           vvvveeeerrrrtttteeeexxxx____hhhhddddllll____tttt _o_w_n_e_r))))
  21.  
  22.      iiiinnnntttt
  23.      ppppcccciiiiiiiioooo____iiiinnnnttttrrrr____ccccoooonnnnnnnneeeecccctttt((((
  24.           ppppcccciiiiiiiioooo____iiiinnnnttttrrrr____tttt _i_n_t_r,,,,
  25.           iiiinnnnttttrrrr____ffffuuuunnnncccc____tttt _f_u_n_c,,,,
  26.           iiiinnnnttttrrrr____aaaarrrrgggg____tttt _a_r_g,,,,
  27.           vvvvooooiiiidddd ****_t_h_r_e_a_d))))
  28.  
  29.      vvvvooooiiiidddd
  30.      ppppcccciiiiiiiioooo____iiiinnnnttttrrrr____ddddiiiissssccccoooonnnnnnnneeeecccctttt((((ppppcccciiiiiiiioooo____iiiinnnnttttrrrr____tttt _i_n_t_r))))
  31.  
  32.      vvvvooooiiiidddd
  33.      ppppcccciiiiiiiioooo____iiiinnnnttttrrrr____ffffrrrreeeeeeee((((ppppcccciiiiiiiioooo____iiiinnnnttttrrrr____tttt _i_n_t_r))))
  34.  
  35.    AAAArrrrgggguuuummmmeeeennnnttttssss
  36.      _a_r_g     A parameter to pass to _f_u_n_c() when this particular interrupt
  37.              occurs, commonly a pointer to a driver-private data structure.
  38.  
  39.      _d_e_s_c    A device descriptor, usually zero.
  40.  
  41.      _f_u_n_c    The function to perform interrupt service.
  42.  
  43.      _i_n_t_r    The interrupt channel handle returned by _p_c_i_i_o__i_n_t_r__a_l_l_o_c().
  44.  
  45.      _l_i_n_e_s   Specifies one or more of the PCI Interrupt pins used by the
  46.              device.
  47.  
  48.      _o_w_n_e_r   An appropriate vertex handle to use when printing messages about
  49.              this particular interrupt, and is usually a vertex created by the
  50.              device driver.
  51.  
  52.      _v_h_d_l    The PCI device connection point as passed to the driver _a_t_t_a_c_h()
  53.              entry point.
  54.  
  55.      _t_h_r_e_a_d  Reserved, should be NULL.
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ppppcccciiiiiiiioooo____iiiinnnnttttrrrr((((DDDD3333))))                                                  ppppcccciiiiiiiioooo____iiiinnnnttttrrrr((((DDDD3333))))
  71.  
  72.  
  73.  
  74. DESCRIPTION
  75.      When a device driver wishes to accept interrupt events from a device, the
  76.      system needs to make sure that there is a path from the PCI interrupt pin
  77.      to the appropriate CPU interrupt hardware.  This is split into two
  78.      separate phases, establishing the channel and connecting a service
  79.      function, so that the service function can be changed or disconnected
  80.      without losing the allocated hardware resources.
  81.  
  82.      The driver is responsible for connecting an interrupt handler when the
  83.      device needs one, and for disconnecting the handler when it does not.
  84.  
  85.      The interrupt delivery mechanism depends on the address of the interrupt
  86.      function.  It is important to disconnect interrupts before a driver
  87.      unloads, otherwise the PCI infrastructure might call a nonexistent
  88.      function.  (A driver cannot be auto-loaded when an interrupt occurs.)
  89.  
  90.      The necessary sequence of calls is based on the use of the driver entry
  91.      points, as follows:
  92.  
  93.      _r_e_g()       Driver registers to handle a class of PCI devices, triggering
  94.                  _a_t_t_a_c_h() calls.
  95.  
  96.      _a_t_t_a_c_h()    Driver calls _p_c_i_i_o__i_n_t_r__a_l_l_o_c() to established interrupt
  97.                  connectivity between the device and the processor.  The
  98.                  designated interrupts are disabled at this point.  If
  99.                  interrupts can occur and are needed at this time, a call to
  100.                  _p_c_i_i_o__i_n_t_r__c_o_n_n_e_c_t() enables interrupts and directs them to
  101.                  the designated handler.
  102.  
  103.      _u_n_l_o_a_d()    The driver is to be unloaded automatically or by operator
  104.                  command.  The driver text is going to be removed, so it is
  105.                  important for all interrupts to be disconnected.
  106.                  _p_c_i_i_o__i_t_e_r_a_t_e() can be used to apply to each of the driver's
  107.                  connection points, a function that can calls
  108.                  _p_c_i_i_o__i_n_t_r__d_i_s_c_o_n_n_e_c_t() as appropriate.  It is not necessary
  109.                  or desirable to call _p_c_i_i_o__i_n_t_r__f_r_e_e() at this time.
  110.  
  111.      _i_n_i_t()      The device driver is being loaded or reloaded.  It can again
  112.                  use _p_c_i_i_o__i_t_e_r_a_t_e(), this time to call a function that re-
  113.                  connects interrupts to the new addresses of their service
  114.                  functions.  No special logic is needed to avoid this at the
  115.                  initial load time, because _p_c_i_i_o__i_t_e_r_a_t_e() is a no-operation
  116.                  when the device driver is not registered.
  117.  
  118.      _d_e_t_a_c_h()    A device is being detached and will no longer be accessible.
  119.                  The driver calls both _p_c_i_i_o__i_n_t_r__d_i_s_c_o_n_n_e_c_t() and
  120.                  _p_c_i_i_o__i_n_t_r__f_r_e_e() for this particular device.
  121.  
  122.      _u_n_r_e_g()     The device driver is shutting down.  It calls
  123.                  _p_c_i_i_o__d_r_i_v_e_r__u_n_r_e_g_i_s_t_e_r().  This triggers a call to the
  124.                  _d_e_t_a_c_h() entry point for every attached device.
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ppppcccciiiiiiiioooo____iiiinnnnttttrrrr((((DDDD3333))))                                                  ppppcccciiiiiiiioooo____iiiinnnnttttrrrr((((DDDD3333))))
  137.  
  138.  
  139.  
  140.      Some devices do not require interrupt service when they are not open.
  141.      Leaving an interrupt allocated but not connected keeps the interrupt
  142.      disabled, possibly reducing impact on the system from handling interrupts
  143.      from devices that do not actually need service.
  144.  
  145.      If this is the situation, then the scenario above may be somewhat
  146.      simplified:
  147.  
  148.      _a_t_t_a_c_h()    Allocate the interrupt to establish a connection and disable
  149.                  the interrupt.  Only connect the interrupt if interrupts are
  150.                  required as part of device initialization; then disconnect
  151.                  it.
  152.  
  153.      _o_p_e_n()      If the interrupt is not yet connected, connect it.
  154.  
  155.      _c_l_o_s_e()     No processes have the device open; disconnect the interrupt
  156.                  when all pending I/O is complete or purged.
  157.  
  158.      _u_n_l_o_a_d()    The driver is not called to unload when one of its devices is
  159.                  open, so no interrupts should be connected.
  160.  
  161.      _d_e_t_a_c_h()    Devices are closed before detaching, so no interrupts should
  162.                  be connected.
  163.  
  164.    SSSSppppeeeecccciiiiffffyyyyiiiinnnngggg PPPPCCCCIIII IIIInnnntttteeeerrrrrrrruuuupppptttt LLLLiiiinnnneeeessss
  165.      The _l_i_n_e_s parameter is formed by or-ing together appropriate flags:
  166.  
  167.           PCIIO_INTR_LINE_A
  168.           PCIIO_INTR_LINE_B
  169.           PCIIO_INTR_LINE_C
  170.           PCIIO_INTR_LINE_D
  171.  
  172. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  173.      Here is how a typical PCI device driver might get interrupt service
  174.      started.
  175.      ppppcccciiiiffffoooooooo____aaaattttttttaaaacccchhhh((((vvvveeeerrrrtttteeeexxxx____hhhhddddllll____tttt ppppccccoooonnnnnnnn____vvvvhhhhddddllll))))
  176.      {{{{
  177.           ppppcccciiiiiiiioooo____iiiinnnnttttrrrr____tttt   iiiinnnnttttrrrr;;;;
  178.           ............
  179.           ////**** TTTThhhhiiiissss ddddeeeevvvviiiicccceeee uuuusssseeeessss bbbbooootttthhhh IIIINNNNTTTTAAAA aaaannnndddd IIIINNNNTTTTBBBB,,,,
  180.            **** aaaannnndddd tttthhhhiiiissss ddddrrrriiiivvvveeeerrrr wwwwaaaannnnttttssss bbbbooootttthhhh rrrroooouuuutttteeeedddd ttttoooo
  181.            **** tttthhhheeee ssssaaaammmmeeee iiiinnnntttteeeerrrrrrrruuuupppptttt sssseeeerrrrvvvviiiicccceeee ffffuuuunnnnccccttttiiiioooonnnn....
  182.            ****////
  183.           iiiinnnnttttrrrr ==== ppppcccciiiiiiiioooo____iiiinnnnttttrrrr____aaaalllllllloooocccc((((ppppccccoooonnnnnnnn____vvvvhhhhddddllll,,,, 0000,,,,
  184.                PPPPCCCCIIIIIIIIOOOO____IIIINNNNTTTTRRRR____LLLLIIIINNNNEEEE____AAAA||||
  185.                PPPPCCCCIIIIIIIIOOOO____IIIINNNNTTTTRRRR____LLLLIIIINNNNEEEE____BBBB,,,,
  186.                ppppcccciiiiffffoooooooo____vvvvhhhhddddllll))));;;;
  187.           ppppcccciiiiiiiioooo____iiiinnnnttttrrrr____ccccoooonnnnnnnneeeecccctttt((((iiiinnnnttttrrrr,,,,
  188.                ppppcccciiiiffffoooooooo____iiiinnnnttttrrrr,,,,
  189.                ((((iiiinnnnttttrrrr____aaaarrrrgggg____tttt))))ppppcccciiiiffffoooooooo____ssssoooofffftttt,,,,
  190.                ((((vvvvooooiiiidddd ****))))0000))));;;;
  191.           ............
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. ppppcccciiiiiiiioooo____iiiinnnnttttrrrr((((DDDD3333))))                                                  ppppcccciiiiiiiioooo____iiiinnnnttttrrrr((((DDDD3333))))
  203.  
  204.  
  205.  
  206.      }}}}
  207.  
  208. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  209.      pciio(D3), pciio_config(D3), pciio_dma(D3), pciio_error(D3),
  210.      pciio_get(D3), pciio_pio(D3).
  211.  
  212. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  213.      _p_c_i_i_o__i_n_t_r__a_l_l_o_c() returns a null value if it can not allocate memory.
  214.  
  215.      _p_c_i_i_o__i_n_t_r__c_o_n_n_e_c_t() returns a zero for success or a negative value on
  216.      failure.  Since the channel is preallocated, the only interesting failure
  217.      for this function is the attempt to use a null interrupt handle value.
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.